<!--
  Licensed to the Apache Software Foundation (ASF) under one or more
  contributor license agreements.  See the NOTICE file distributed with
  this work for additional information regarding copyright ownership.
  The ASF licenses this file to You under the Apache License, Version 2.0
  (the "License"); you may not use this file except in compliance with
  the License.  You may obtain a copy of the License at

      http://www.apache.org/licenses/LICENSE-2.0

  Unless required by applicable law or agreed to in writing, software
  distributed under the License is distributed on an "AS IS" BASIS,
  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  See the License for the specific language governing permissions and
  limitations under the License.
-->
<body>
<h2> JMX MBeans. </h2>
When Derby (the embedded engine) is booted it will attempt to connect
to the PlatformMBeanServer and register a number of MBeans to monitor and manage Derby.
<P>
Derby registers its JMX MBeans in the <code>org.apache.derby</code> domain and
always includes values for <code>type</code> and <code>system</code> in the MBean's ObjectName's key
properties. Other key properties are described in the interface class for the MBean.
<UL>
<LI> <code>type</code> Set to the class name of the MBean's interface class without
the package and without <code>MBean</code>. E.g. for <code>org.apache.derby.mbeans.VersionMBean</code>
the key property <code>type</code> will be set to <code>Version</code>. The javadoc for each MBean
also indicates what <code>type</code> will be set to.
<LI> <code>system</code> Set to a runtime identifier that allows Derby and applications
to disambiguate multiple Derby systems in the same virtual machine but different class loaders.
Currently a new value is created each time Derby is booted. An application may discover the
value of the identifier by registering the MBean <code>org.apache.derby.mbeans.Management</code>
and accessing the <code>SystemIdentifier</code>. This application created <code>ManagementMBean</code>
must be running in the same class loader as Derby.
</UL>
<P>
Derby registers the class name for any MBean to be the interface class for the MBean
(i.e. <code>org.apache.derby.mbeans.*MBean</code>) to hide the implementation class
(which is subject to change). Permissions in policy files therefore need to
use the MBean interface to define fine grained access. E.g. the permission 
to allow a invoking the <code>startManagement</code> of the <code>ManagementMBean</code>
may be written as:
<pre>
permission javax.management.MBeanPermission
    "org.apache.derby.mbeans.ManagementMBean#startManagement[org.apache.derby:*]",
    "invoke";
</pre>
<P>
If Derby cannot connect to the PlatformMBeanServer then no MBeans will be registered.
Applications may use the <code>org.apache.derby.mbeans.Management</code> MBean to
later enable Derby's JMX management.
<P>
If Derby cannot register a specific MBean (e.g. due to no permission to register
that MBean) then it will simply be ignored. Subsequent re-starts of Derby's
management service through <code>org.apache.derby.mbeans.ManagementMBean</code> will
attempt to register such an MBean again (assuming it is still valid),
in case the security policy has been updated.
</body>
